Commit XA (QxdaXACommit) API

A transaction manager calls QxdaXACommit() to commit the work associated with the transaction branch identifier. All changes that were made to resources managed by DB2^® for IBM^® i during the transaction branch are made permanent. The connection does not have to be associated with the transaction in any way.

Authorities and Locks

None.

Required Parameter Group

Connection handle

INPUT; BINARY(4)

The handle number of the connection on which to perform the XA operation. The connection handle must have been generated by the QxdaConnectEDRS API in the current job and activation group.

Transaction branch identifier

INPUT; CHAR(*)

The transaction branch identifier. This identifier is generated by the transaction manager when it starts the transaction branch. The max length is 140 bytes.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Format identifier
4	4	BINARY(4)	Length of global transaction identifier
8	8	BINARY(4)	Length of branch qualifier
12	C	CHAR(128)	Transaction branch identifier

Format identifier:	Identifies the naming format being used. If OSI CCR naming is used, the format identifier should be set to 0. If some other format is used, a the value should be greater than 0. A value of -1 means the transaction branch identifier is null.
Length of global transaction identifier:	Identifies the first of at most two contiguous components comprised by the data field. This specifies the number of bytes (1-64) starting at the first byte of the data element. This is not null-terminated.
Length of branch qualifier:	Identifies the second of at most two contiguous components comprised by the data field. This specifies the number of bytes (1-64) starting at the first byte after the global transaction identifier. This is not null-terminated.
Transaction branch identifier:	Contains the data of the transaction branch identifier

Return value

OUTPUT; BINARY(4)

The return value of the XA operation. The following values may be returned only if TMONEPHASE(x40000000) was set in the flags parameter:

100	[XA_RBROLLBACK]	The transaction branch was rolled back for an unspecified reason.
101	[XA_RBCOMMFAIL]	The transaction was rolled back because a communications failure occurred within the resource manager.
102	[XA_RBDEADLOCK]	The transaction was rolled back because a deadlock condition was detected within the resource manager.
103	[XA_RBINTEGRITY]	The transaction was rolled back because the resource manager detected a violation of the integrity of its resources.
104	[XA_RBOTHER]	The resource manager rolled back the transaction branch for a reason not on this list.
105	[XA_RBPROTO]	The transaction was rolled back because a protocol error occurred in the resource manager.
106	[XA_RBTIMEOUT]	The transaction was rolled back because a timeout occurred in the resource manager.
107	[XA_RBTRANSIENT]	The transaction was rolled back because a transient error was detected in the resource manager.

The following values may be returned for all flag settings.

-7	[XAER_RMFAIL]	An error occurred that makes the resource manager unavailable.
-6	[XAER_PROTO]	xa_commit() was not successful. Function was called in an improper context.
-5	[XAER_INVAL]	xa_commit() was not successful. Incorrect arguments were specified.
-4	[XAER_NOTA]	The specified xid is not known by the resource manager.
-3	[XAER_RMERR]	xa_commit() was not successful. The resource manager detected an error when committing the transaction branch.
-2	[XAER_ASYNC]	xa_commit() was not successful. The resource manager does not support asynchronous operations.
0	[XA_OK]	xa_commit() was successful.
4	[XA_RETRY]	The resource manager is unable to commit the transaction branch at this time. TMNOWAIT(x10000000) was set and a blocking condition exists. All resources held on behalf of *xid remain in a prepared state. The transaction manager should issue xa_commit() again at a later time.
5	[XA_HEURMIX]	Work on the transaction branch was partially committed and partially rolled back.
6	[XA_HEURRB]	Work on the transaction branch was heuristically rolled back.
7	[XA_HEURCOM]	Work on the transaction branch was heuristically committed.
8	[XA_HEURHAZ]	Work on the transaction branch may have been heuristically completed.

Flags

INPUT; BINARY(4)

Indicator of how to perform the XA operation. The following are valid settings of flags:

TMNOWAIT:	x10000000	Do not commit the transaction if a blocking condition exists.
TMONEPHASE:	x40000000	Use the one-phase commit optimization for the specified transaction branch.
TMNOFLAGS:	x00000000	Use if no other flags are set.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Usage Notes

This function may be called from the initial thread of a job only.

Error Messages

Related Information

The QxdaXA APIs follow the NTS (transactions with transaction scoped locks) model. For more information regarding the NTS model, see XA APIs.

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include qxdaedrs.h 

main()
{ 
err_t     err; 
Qxda_CDBI0100_t *istr = (Qxda_CDBI0100_t *)instruct;
Qxda_CDBO0100_t  ostr;
int ostrsize;
XID inxid;
char gtrid[8] = "TestXA";
char bqual[6] = "Test"; 
inxid.formatID = 0;  
inxid.gtrid_length = 6; 
inxid.bqual_length = 4; 
int create = XDA_SQL_TXN_CREATE;
int end = XDA_SQL_TXN_END; 
int timeoutval = 60;
Qsq_sqlca_t      myca; 
int   stmt1len = 21;
int flags = 0; 
int ret_val; 
_CPYBYTES(dtaara, gtrid, inxid.gtrid_length); 
_CPYBYTES(dtaara + inxid.gtrid_length, bqual, inxid.bqual_length);   
_CPYBYTES(inxid.data, dtaara, inxid.gtrid_length + inxid.bqual_length); 
XID *xid = &inxid;




 memset(istr, '\0', sizeof(Qxda_CDBI0100_t));                  


 istr->Connection_Type = 'U';                                                        
 memset(istr->Server_Name, ' ', 256);                  
 istr->Commitment_Control = 'S';                          
 _CPYBYTES(istr->Commit_Scope, "*XA                      ", 10);         
 istr->Allow_Suspend = 'Y';
 memset(istr->RDB_Specified, '0', 1);
 istr->SQLDA_Cache_Size = 10;                             
 istr->Offset_Job_Data = sizeof(Qxda_CDBI0100_t);         
 istr->Length_Job_Data = 7;                               
 _CPYBYTES((char *)istr + istr->Offset_Job_Data, "CONNECT", 7);   
 istr->Offset_Suspend_Data = istr->Offset_Job_Data + istr->Length_Job_Data; 
 istr->Length_Suspend_Data = 7;   
 memset(istr->RDB_Name, ' ', 18);
 _CPYBYTES(istr->TM_Info, "TM_Name         ", 10); 
 istr->LockTimeoutVal = 10;  
 ostrsize = sizeof(Qxda_CDBO0100_t);                                        


 QxdaConnectEDRS(istr, "CDBI0100", &ostr, &ostrsize,
                  "CDBO0100", &err);


 QxdaSetXaConnection(&ostr.Connection_Handle, xid, &ret_val, &create, &timeoutval, &err);

 QxdaProcessImmediateEDRS(&ostr.Connection_Handle,
              "SELECT * FROM MYTABLE", &stmt1len, &myca, &err); 


 QxdaSetXaConnection(&ostr.Connection_Handle, xid, &ret_val, &end, &timeoutval, &err);


 QxdaXAPrepare(&ostr.Connection_Handle, xid, &ret_val, &flags, &err);

 QxdaXACommit(&ostr.Connection_Handle, xid, &ret_val, &flags, &err);

} 

[ Back to top | Database and File APIs | APIs by category ]